home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / X11 / XCreateFontSet.z / XCreateFontSet
Encoding:
Text File  |  1998-10-30  |  13.1 KB  |  265 lines
  1.  
  2.  
  3.  
  4.      XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....3333))))XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))
  5.  
  6.  
  7.  
  8.      NNNNAAAAMMMMEEEE
  9.           XCreateFontSet, XFreeFontSet - create and free an
  10.           international text drawing font set
  11.  
  12.      SSSSYYYYNNNNTTTTAAAAXXXX
  13.           XFontSet XCreateFontSet(_d_i_s_p_l_a_y, _b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t,
  14.           _m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n,
  15.                          _m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n,
  16.           _d_e_f__s_t_r_i_n_g__r_e_t_u_r_n)
  17.                 Display *_d_i_s_p_l_a_y;
  18.                 char *_b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t;
  19.                 char ***_m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n;
  20.                 int *_m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n;
  21.                 char **_d_e_f__s_t_r_i_n_g__r_e_t_u_r_n;
  22.  
  23.           void XFreeFontSet(_d_i_s_p_l_a_y, _f_o_n_t__s_e_t)
  24.                 Display *_d_i_s_p_l_a_y;
  25.                 XFontSet _f_o_n_t__s_e_t;
  26.  
  27.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  28.           _d_i_s_p_l_a_y   Specifies the connection to the X server.
  29.  
  30.           _b_a_s_e__f_o_n_t__n_a_m_e__l_i_s_t
  31.                     Specifies the base font names.
  32.  
  33.           _d_e_f__s_t_r_i_n_g__r_e_t_u_r_n
  34.                     Returns the string drawn for missing charsets.
  35.  
  36.           _f_o_n_t__s_e_t  Specifies the font set.
  37.  
  38.           _m_i_s_s_i_n_g__c_h_a_r_s_e_t__c_o_u_n_t__r_e_t_u_r_n
  39.                     Returns the number of missing charsets.
  40.  
  41.           _m_i_s_s_i_n_g__c_h_a_r_s_e_t__l_i_s_t__r_e_t_u_r_n
  42.                     Returns the missing charsets.
  43.  
  44.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  45.           The _X_C_r_e_a_t_e_F_o_n_t_S_e_t function creates a font set for the
  46.           specified display.  The font set is bound to the current
  47.           locale when _X_C_r_e_a_t_e_F_o_n_t_S_e_t is called.  The font set may be
  48.           used in subsequent calls to obtain font and character
  49.           information and to image text in the locale of the font set.
  50.  
  51.           The base_font_name_list argument is a list of base font
  52.           names that Xlib uses to load the fonts needed for the
  53.           locale.  The base font names are a comma-separated list.
  54.           The string is null-terminated and is assumed to be in the
  55.           Host Portable Character Encoding; otherwise, the result is
  56.           implementation-dependent.  White space immediately on either
  57.           side of a separating comma is ignored.
  58.  
  59.           Use of XLFD font names permits Xlib to obtain the fonts
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 4/30/98)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....3333))))XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))
  71.  
  72.  
  73.  
  74.           needed for a variety of locales from a single locale-
  75.           independent base font name.  The single base font name
  76.           should name a family of fonts whose members are encoded in
  77.           the various charsets needed by the locales of interest.
  78.  
  79.           An XLFD base font name can explicitly name a charset needed
  80.           for the locale.  This allows the user to specify an exact
  81.           font for use with a charset required by a locale, fully
  82.           controlling the font selection.
  83.  
  84.           If a base font name is not an XLFD name, Xlib will attempt
  85.           to obtain an XLFD name from the font properties for the
  86.           font.  If this action is successful in obtaining an XLFD
  87.           name, the _X_B_a_s_e_F_o_n_t_N_a_m_e_L_i_s_t_O_f_F_o_n_t_S_e_t function will return
  88.           this XLFD name instead of the client-supplied name.
  89.  
  90.           Xlib uses the following algorithm to select the fonts that
  91.           will be used to display text with the _X_F_o_n_t_S_e_t.
  92.  
  93.           For each font charset required by the locale, the base font
  94.           name list is searched for the first appearance of one of the
  95.           following cases that names a set of fonts that exist at the
  96.           server:
  97.  
  98.           +o    The first XLFD-conforming base font name that specifies
  99.                the required charset or a superset of the required
  100.                charset in its _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g
  101.                fields.  The implementation may use a base font name
  102.                whose specified charset is a superset of the required
  103.                charset, for example, an ISO8859-1 font for an ASCII
  104.                charset.
  105.  
  106.           +o    The first set of one or more XLFD-conforming base font
  107.                names that specify one or more charsets that can be
  108.                remapped to support the required charset.  The Xlib
  109.                implementation may recognize various mappings from a
  110.                required charset to one or more other charsets and use
  111.                the fonts for those charsets.  For example, JIS Roman
  112.                is ASCII with tilde and backslash replaced by yen and
  113.                overbar; Xlib may load an ISO8859-1 font to support
  114.                this character set if a JIS Roman font is not
  115.                available.
  116.  
  117.           +o    The first XLFD-conforming font name or the first non-
  118.                XLFD font name for which an XLFD font name can be
  119.                obtained, combined with the required charset (replacing
  120.                the _C_h_a_r_S_e_t_R_e_g_i_s_t_r_y and _C_h_a_r_S_e_t_E_n_c_o_d_i_n_g fields in the
  121.                XLFD font name).  As in case 1, the implementation may
  122.                use a charset that is a superset of the required
  123.                charset.
  124.  
  125.           +o    The first font name that can be mapped in some
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 4/30/98)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....3333))))XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))
  137.  
  138.  
  139.  
  140.                implementation-dependent manner to one or more fonts
  141.                that support imaging text in the charset.
  142.  
  143.           For example, assume that a locale required the charsets:
  144.  
  145.           ISO8859-1
  146.           JISX0208.1983
  147.           JISX0201.1976
  148.           GB2312-1980.0
  149.  
  150.           The user could supply a base_font_name_list that explicitly
  151.           specifies the charsets, ensuring that specific fonts are
  152.           used if they exist.  For example:
  153.  
  154.           "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240-JISX0208.1983-0,\
  155.           -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120-JISX0201.1976-0,\
  156.           -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240-GB2312-1980.0,\
  157.           -Adobe-Courier-Bold-R-Normal--25-180-75-75-M-150-ISO8859-1"
  158.  
  159.           Alternatively, the user could supply a base_font_name_list
  160.           that omits the charsets, letting Xlib select font charsets
  161.           required for the locale.  For example:
  162.  
  163.           "-JIS-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
  164.           -JIS-Fixed-Medium-R-Normal--26-180-100-100-C-120,\
  165.           -GB-Fixed-Medium-R-Normal--26-180-100-100-C-240,\
  166.           -Adobe-Courier-Bold-R-Normal--25-180-100-100-M-150"
  167.  
  168.           Alternatively, the user could simply supply a single base
  169.           font name that allows Xlib to select from all available
  170.           fonts that meet certain minimum XLFD property requirements.
  171.           For example:
  172.  
  173.           "-*-*-*-R-Normal--*-180-100-100-*-*"
  174.  
  175.           If _X_C_r_e_a_t_e_F_o_n_t_S_e_t is unable to create the font set, either
  176.           because there is insufficient memory or because the current
  177.           locale is not supported, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL,
  178.           missing_charset_list_return is set to NULL, and
  179.           missing_charset_count_return is set to zero.  If fonts exist
  180.           for all of the charsets required by the current locale,
  181.           _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a valid _X_F_o_n_t_S_e_t,
  182.           missing_charset_list_return is set to NULL, and
  183.           missing_charset_count_return is set to zero.
  184.  
  185.           If no font exists for one or more of the required charsets,
  186.           _X_C_r_e_a_t_e_F_o_n_t_S_e_t sets missing_charset_list_return to a list of
  187.           one or more null-terminated charset names for which no font
  188.           exists and sets missing_charset_count_return to the number
  189.           of missing fonts.  The charsets are from the list of the
  190.           required charsets for the encoding of the locale and do not
  191.           include any charsets to which Xlib may be able to remap a
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 4/30/98)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))XXXX VVVVeeeerrrrssssiiiioooonnnn 11111111 ((((RRRReeeelllleeeeaaaasssseeee 6666....3333))))XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttSSSSeeeetttt((((3333XXXX11111111))))
  203.  
  204.  
  205.  
  206.           required charset.
  207.  
  208.           If no font exists for any of the required charsets or if the
  209.           locale definition in Xlib requires that a font exist for a
  210.           particular charset and a font is not found for that charset,
  211.           _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns NULL.  Otherwise, _X_C_r_e_a_t_e_F_o_n_t_S_e_t
  212.           returns a valid _X_F_o_n_t_S_e_t to font_set.
  213.  
  214.           When an Xmb/wc drawing or measuring function is called with
  215.           an _X_F_o_n_t_S_e_t that has missing charsets, some characters in
  216.           the locale will not be drawable.  If def_string_return is
  217.           non-NULL, _X_C_r_e_a_t_e_F_o_n_t_S_e_t returns a pointer to a string that
  218.           represents the glyphs that are drawn with this _X_F_o_n_t_S_e_t when
  219.           the charsets of the available fonts do not include all font
  220.           glyphs required to draw a codepoint.  The string does not
  221.           necessarily consist of valid characters in the current
  222.           locale and is not necessarily drawn with the fonts loaded
  223.           for the font set, but the client can draw and measure the
  224.           default glyphs by including this string in a string being
  225.           drawn or measured with the _X_F_o_n_t_S_e_t.
  226.  
  227.           If the string returned to def_string_return is the empty
  228.           string (""), no glyphs are drawn, and the escapement is
  229.           zero.  The returned string is null-terminated.  It is owned
  230.           by Xlib and should not be modified or freed by the client.
  231.           It will be freed by a call to _X_F_r_e_e_F_o_n_t_S_e_t with the
  232.           associated _X_F_o_n_t_S_e_t.  Until freed, its contents will not be
  233.           modified by Xlib.
  234.  
  235.           The client is responsible for constructing an error message
  236.           from the missing charset and default string information and
  237.           may choose to continue operation in the case that some fonts
  238.           did not exist.
  239.  
  240.           The returned _X_F_o_n_t_S_e_t and missing charset list should be
  241.           freed with _X_F_r_e_e_F_o_n_t_S_e_t and _X_F_r_e_e_S_t_r_i_n_g_L_i_s_t, respectively.
  242.           The client-supplied base_font_name_list may be freed by the
  243.           client after calling _X_C_r_e_a_t_e_F_o_n_t_S_e_t.
  244.  
  245.           The _X_F_r_e_e_F_o_n_t_S_e_t function frees the specified font set.  The
  246.           associated base font name list, font name list, _X_F_o_n_t_S_t_r_u_c_t
  247.           list, and _X_F_o_n_t_S_e_t_E_x_t_e_n_t_s, if any, are freed.
  248.  
  249.      SSSSEEEEEEEE AAAALLLLSSSSOOOO
  250.           XExtentsofFontSet(3X11), XFontsOfFontSet(3X11),
  251.           XFontSetExtents(3X11)
  252.           _X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 4/30/98)
  262.  
  263.  
  264.  
  265.